Empezar a usar photoshelf

01 — Antes de empezar

Qué vas a necesitar

photoshelf funciona en dos piezas que trabajan juntas. No hace falta entender los detalles técnicos, pero sí conviene tener claro qué es cada una para no perderte:

• El agente — el instalador (.dmg, .exe o .AppImage) que te han pasado. Se instala en tu ordenador, vigila las carpetas donde guardas tus fotos y las sincroniza con tu photoshelf.
• Tu photoshelf — la biblioteca web propiamente dicha: la ves y la usas desde el navegador, en una dirección propia. Puede ser un dominio en la nube como https://getphotoshelf.com si usáis la versión alojada, o una dirección local tipo http://192.168.1.50:3000 si alguien la tiene autoalojada en su propio NAS o servidor. En ambos casos funciona igual — solo cambia dónde vive.

Antes de instalar nada, pide a esa persona dos cosas:

1. La dirección de tu photoshelf (la URL a la que te conectarás).
2. Tu usuario: si eres la primera persona en usar esa instalación, te registras tú mismo como administrador desde esa dirección; si no, recibirás una invitación por correo con una contraseña temporal.

02 — Instalación

Instala el agente en tu ordenador

El agente está disponible para Mac, Windows y Linux. Es una aplicación pequeña, con un icono que vive en la barra de menús (Mac) o la bandeja del sistema (Windows) mientras trabaja en segundo plano.

macOS (.dmg)

1. Abre el archivo .dmg y arrastra la app a tu carpeta Aplicaciones.
2. Al abrirla por primera vez, macOS mostrará un aviso de que «la app está dañada y no se puede abrir». No lo está — es que el instalador no lleva la firma de pago de Apple. Abre Terminal y ejecuta, sustituyendo la ruta por la tuya:

   xattr -cr "/Applications/nombre-de-la-app.app"

3. Vuelve a abrir la app con doble clic. Esta vez arrancará con normalidad.

Windows (.exe)

1. Ejecuta el instalador. Windows SmartScreen probablemente avise de que «no se reconoce la app» — es la misma razón que en Mac, el instalador no está firmado.
2. Haz clic en Más información y luego en Ejecutar de todas formas.
3. Sigue el asistente de instalación hasta el final.

Linux (.AppImage)

1. Dale permiso de ejecución al archivo y lánzalo:

   chmod +x photoshelf-agent.AppImage
   ./photoshelf-agent.AppImage

03 — Primer arranque

Conéctate a tu photoshelf

Al abrir el agente por primera vez te pedirá dos datos:

• La dirección de tu servidor (la URL que te han pasado).
• Tu email y contraseña — los mismos con los que entrarías desde el navegador.

Una vez inicias sesión, el agente guarda tus credenciales de forma segura en el llavero de tu sistema operativo (Llavero de macOS, Administrador de credenciales de Windows) — nunca en un archivo de texto plano. No hace falta volver a iniciar sesión cada vez que abras el agente.

A partir de aquí el agente queda residente: verás su icono en la barra de menús o la bandeja del sistema. Ciérralo desde ahí cuando quieras dejar de sincronizar; mientras esté abierto, trabaja en segundo plano sin que tengas que hacer nada más.

04 — Catálogo

Indica dónde están tus fotos

photoshelf no escanea todo tu disco: tú eliges qué carpeta es tu catálogo, y dentro de esa carpeta espera una estructura concreta por año y evento:

Mis fotos/
  2024/
    Vacaciones en Japón/
      IMG_0001.jpg
      IMG_0002.jpg
    Cumpleaños de mamá/
      foto.png
  2023/
    Boda de Julia y Marc/
      ...

• La carpeta de primer nivel debe empezar por un año numérico (2023, 2024...). Cualquier carpeta que no siga ese patrón se ignora — no rompe nada, simplemente no se sincroniza.
• Dentro de cada año, cada subcarpeta es un evento: el nombre es libre, úsalo como te resulte natural (Boda de Julia y Marc, Viaje a Japón...).
• Formatos de foto admitidos: .jpg, .jpeg, .png, .heic, .heif, .webp, .tif, .tiff, .avif.

Desde el agente, señala esa carpeta raíz como tu catálogo. Puedes tener más de un catálogo (por ejemplo, uno por disco externo) y también sincronizar el mismo catálogo desde varios ordenadores — el NAS y tu portátil a la vez, por ejemplo — porque cada catálogo se identifica por nombre, no por dispositivo. Si hay años o eventos concretos que no quieres subir, puedes excluirlos desde el propio agente.

05 — Sincronización

Cómo sincroniza el agente

Con el catálogo configurado, el agente vigila esa carpeta en tiempo real. Cada vez que detecta un cambio, hace lo siguiente:

1. Lee la fecha, la cámara y demás datos técnicos (EXIF) de cada foto nueva.
2. Genera una miniatura de alta calidad y comprueba de paso que el archivo se abre bien; si está dañado, lo excluye y lo marca como corrupto — sin moverlo ni borrarlo de tu disco.
3. Si tienes la clasificación por IA activada, etiqueta la foto en tu propio ordenador antes de subir nada.
4. Sube la miniatura y los datos a tu photoshelf.
5. Si borras una foto ya sincronizada de una carpeta que no está excluida, el agente la borra también del servidor, sin pedir confirmación.

06 — La biblioteca

Tu biblioteca en el navegador

Con el agente sincronizando, entra a la dirección de tu photoshelf desde cualquier navegador (ordenador o móvil) e inicia sesión con tu email y contraseña. Esto es lo que te vas a encontrar:

En el móvil, la biblioteca cambia a un visor a pantalla completa con gestos de deslizar y un panel de información deslizable desde abajo — pensado para explorar con el pulgar, no para gestionar catálogos.

07 — Inteligencia artificial

Inteligencia artificialOpcional

La IA en photoshelf interviene en dos momentos distintos, y merece la pena diferenciarlos:

En el agente: clasificación local

Si activas la visión local en el agente, cada foto se etiqueta en tu propio ordenador antes de subirla — nunca viaja a ningún sitio para ser analizada. La primera vez que la activas, el agente se encarga de todo automáticamente: comprueba si ya tienes un modelo de IA corriendo, y si no, levanta uno por su cuenta y descarga lo necesario. Verás el progreso reflejado con estos estados:

En tu photoshelf: clasificación, búsqueda y análisis

Desde Ajustes → IA, cada persona elige su propio motor de IA: el compartido del servidor, o uno propio con tu API key de Anthropic u OpenAI. Con eso activado, tu photoshelf puede:

• Sugerir etiquetas automáticas para tus fotos.
• Entender búsquedas en lenguaje natural — «fotos de playa al atardecer» encuentra fotos aunque nunca las hayas etiquetado así.
• Escribir una crítica fotográfica de una imagen: composición, luz, puntos fuertes y débiles, con una puntuación del 1 al 10.
• Proponer y redactar proyectos a partir de tus fotos.
• Generar un análisis de tu estilo fotográfico a lo largo del tiempo.

08 — Compartir

Compartir tus fotos

Tú decides exactamente qué se ve fuera de tu cuenta y quién puede verlo. Hay dos formas de compartir:

• Proyectos publicados — cada proyecto que edites puede publicarse en su propia página pública, con su propia dirección. Opcionalmente puedes protegerlo con una lista de emails autorizados: quien no esté en la lista tendrá que introducir su email antes de ver nada.
• Enlaces temporales — para compartir un grupo de fotos rápido, sin montar un proyecto. Caducan pasado un tiempo y no requieren que quien los reciba tenga cuenta ni inicie sesión.

En ningún caso compartir un proyecto o un enlace da acceso al resto de tu biblioteca — solo a lo que has incluido explícitamente.

09 — Copias y salud

Copias de seguridad y salud de la biblioteca

Desde Ajustes → Catálogos puedes hacer una copia de seguridad manual en cualquier momento, o dejar que se haga sola cada cierto número de días. Se guarda un historial con las últimas copias por si necesitas volver atrás.

En Herramientas → Integridad tienes un panel de salud de tu catálogo: archivos que no se pudieron leer, miniaturas huérfanas y posibles duplicados. El agente nunca mueve ni borra nada por iniciativa propia — este panel solo informa, para que decidas tú qué hacer.

10 — Multiusuario

Varias personas, una sola instalación

Un mismo photoshelf puede tener varias cuentas — por ejemplo, cada miembro de una familia con la suya. Cada cuenta tiene sus propios catálogos, fotos, tags, proyectos y configuración de IA, completamente separados del resto: nadie ve las fotos de otra cuenta, ni siquiera quien administra la instalación.

Las cuentas nuevas se crean por invitación desde Ajustes → Usuarios — solo puede hacerlo quien tenga el rol de administrador. Si es tu caso, al invitar a alguien se genera una contraseña temporal que verás una única vez para pasársela.

11 — Ayuda

Si algo no funciona

El agente no consigue conectar

Comprueba que la dirección del servidor está bien escrita (incluyendo http:// o https://) y que tu ordenador tiene acceso a esa red — si tu photoshelf vive en un NAS de casa, necesitas estar en la misma red o tener configurado el acceso remoto.

Mis fotos no aparecen tras sincronizar

Lo más habitual es un problema de estructura de carpetas: revisa que la carpeta de primer nivel empiece por un año numérico, y que el archivo tenga una extensión admitida. Las carpetas que no siguen el formato simplemente se ignoran, sin avisar.

La IA aparece como «no disponible»

Si usas clasificación local en el agente, puede deberse a que el motor de IA local todavía se está preparando la primera vez. Si usas el motor compartido del servidor, puede que esté temporalmente caído o que tu administrador aún no lo haya configurado — contacta con esa persona. En ambos casos, el resto de photoshelf sigue funcionando con normalidad.

He olvidado mi contraseña

El cambio de contraseña desde ajustes todavía no está disponible en esta versión. Pide a quien administra tu instalación que te cree una contraseña temporal nueva desde Ajustes → Usuarios.

«App dañada» en Mac o SmartScreen en Windows

No es un virus: es que el instalador no está firmado digitalmente. Revisa el paso a paso en Instala el agente.